Skip to main content

Microsoft Entra ID

For more information about configuring Microsoft Entra ID, see the Azure documentation.

Entra ID Configuration Steps

  1. In Microsoft Entra , go to Azure Services and select Entra ID. 2. Select "Enterprise Applications" from the navigation panel.

  2. Click "New Application."

  3. Click "Create your own application"

  4. In the Name field, enter a name for the application, such as "Cyberhaven Application."

  5. Go to the Cyberhaven dashboard. On the bottom left-hand corner of the screen, click the PREFERENCES button.

  6. Click AUTHENTICATION PROVIDER, then click ADD NEW.

  7. In the Name field, enter a name, such as "Azure SSO". This field can be any name you prefer.

  8. For the following steps, see the image below that shows the mapping of the fields.

    1. In the "Identity provider entity ID" field, enter the "Azure ID Identifier".

    2. Enter the authorization callback URL to the Azure SSO 'Basic SAML Configuration' -> 'Reply URL'.

    3. Copy / paste your Cyberhaven instance URL into the Entra ID SSO 'Sign on URL' field.

    4. In the Azure 'Basic SAML Configuration' > Identifier (Entity ID) enter a unique string such as 'saml-id'. We recommend including your company name in the string to ensure this is unique.

    5. Go to SAML Signing Certificate > Download 'Certificate (Base64). f. Open the downloaded base64-encoded certificate in a text editor and copy/paste the full contents into the "Certificate" field on the Cyberhaven dashboard.

    6. Go to the Azure SSO dashboard and copy / paste the Entra ID "Login URL" to the Cyberhaven field "SSO URL".

    7. From the Azure SSO dashboard copy/paste the Entra ID "Identifier (Entity ID)" to Cyberhaven field 'Service provider entity ID'.

After you've configured Entra ID as your identity provider, follow the sign-up process described in the SSO Sign-up section.

SSO Sign-up​

When a new user is invited to join the Cyberhaven console, they will receive an email invitation. Clicking the activation link will allow them to choose their desired identity provider. They can click Sign Up with Okta to establish SSO.

For existing users in the Cyberhaven console, you must reset the auth provider for each user.

1. In the Cyberhaven console, navigate to Preferences > Users. 2. Click on the kebab menu for each user and select Reset auth provider.

The users will receive an email invitation with a link to sign up with the identity provider and establish SSO.

NOTE

Ensure that you allow list the Cyberhaven domain cyberhaven.info to receive the email invitation.

Changing Authentication Methods for Existing Users

If you wish to change the authentication method for an existing user, you can do so by browsing to the User Management page, clicking the user in question, and clicking RESET next to Reset Authentication Method.

Validating Authentication Method

You can validate the authentication method assigned to a user, as it will be displayed next to their email address in the User Management console. The presented methods are password, google.com, or SAML.

Known issues​

  1. Using the Okta tile may not authenticate you to your Cyberhaven console. Instead, visit your Cyberhaven instance login page and select "Log in with Okta."

  2. Just-in-time provisioning of users is not supported yet.

Troubleshooting​

  1. If SSO was initially misconfigured, you may need to delete and recreate users in the dashboard for the changes to take effect.

  2. Errors such as "All <AudienceRestriction>s should contain the SAML RP entity ID" can be caused by a mismatch in the Service Provider Entity ID. Verify the configuration as shown in the mapping images for your provider.

  3. The error "GUID values are not supported for Identifier" points to the fact that you are using a Service Provider Identity ID that is not formatted correctly. Try with a simple string such as "cyberhaven" or "saml-id". Ensure to update the string in the Cyberhaven dashboard and your SAML provider configuration page.

  4. The error "Unable to process request due to missing initial state" is likely to be caused by the following two reasons.

The user is trying out an IDP-initiated login which is not supported. For instance, using the tiles in Okta to automatically log into Cyberhaven is not supported. Customers must open the Cyberhaven console and log in with Okta.

The browser session storage is inaccessible or accidentally cleared. Try clearing browser cookies.

  1. The error “Failed to verify the signature in SAML Response” is likely to be caused by an issue with the certificate. Verify that the certificate was correctly copied and pasted.

If you encounter any other errors, create a support ticket and include a screenshot of the configuration on your SAML provider side.

Directories and User Mapping

This feature is available from Cyberhaven version 22.09. Cyberhaven

automatically synchronizes local user groups from on-premises Active Directory and Apple Open Directory whereas, Cyberhaven leverages WorkOS to integrate with cloud directory providers.

The Cyberhaven SaaS service integrates with Cloud Directory providers such as Microsoft Entra ID, Okta, Google, JumpCloud, SCIM, etc. using WorkOS. The integration enables Cyberhaven to map users to user accounts in your directory service to correlate local user activities. Cyberhaven uses the email address in the directory service to map each user since email addresses serve as unique identifiers. By using email-based mapping, Cyberhaven ensures accurate and reliable associations between endpoint users and the user directory.

This mapping is done in the Cyberhaven SaaS service, not by Cyberhaven Endpoint Sensors. When the mapping is complete, sensor-generated events on the Risks Overview page will contain the username as defined in your directory service. You can click on the username to view details such as the user groups related to this user in your directory.

NOTE

This feature only works with directory services that have configured email addresses.

What Directory Information is Available Without Integration

This section refers to what directory information is available without any directory integration. On both Windows and macOS, the Endpoint Sensors are able to automatically synchronize the local user groups. This happens out of the box and does not require any directory integration to be set up. For instance, on Windows, the group information from on-prem Active Directory or Microsoft Entra ID is synchronized by the operating system and available in the user token. This group information is automatically synchronized by Windows when the user logs in (but cannot be synchronized on demand). The Cyberhaven Windows Endpoint Sensor is able to query the user token and extract the group information automatically. Other directory information is not available without configuring the directory integration in the Cyberhaven Console.

Similarly, on macOS, the Sensor will automatically map the endpoint users to their email address setup within Apple Open Directory. However, if you use Jamf in your environment, then we also provide a new MDM profile to set up email based user mapping. Read more: Enhancing User Mapping on macOS with Jamf.

Integrate multiple directories

Cyberhaven can integrate with multiple user directories and correlate information about a user from the different directories. This information is presented in the context of events generated by the user's activities to provide you with a comprehensive understanding of the user's actions. To identify a user across multiple directories, Cyberhaven requires a consistent email address associated with the user in all the directories. Follow the instructions in Integrating Cyberhaven with Cloud-based User Directories to add multiple directories in your Cyberhaven Console.

Integrating Cyberhaven with Cloud-based User Directories

Users are automatically mapped to the email address configured in the user directory. You must integrate Cyberhaven with your cloud directory services to enable email-based user mapping.

To integrate Cyberhaven with your cloud directory services,

1. In the Cyberhaven tenant, navigate to Preferences > Directories and user mapping and click Add New. The WorkOS setup page opens in a new browser tab.

2. On the WorkOS setup page, select the directory provider and follow the setup instructions on the screen. For detailed instructions, follow the WorkOS documentation here, WorkOS Documentation.

When the setup is complete, the directory service is displayed on the Directory Integrations tab. You can click on a linked service in the State column to view the list of users and their usernames.

After integrating with a directory service, the Cyberhaven console synchronizes with WorkOS to update usernames on the Risks Overview page. When updated, the events will show usernames and user groups as per your directory.

The initial synchronization process can take up to 12 hours to complete. After that, the page is updated with directory information every 30 minutes to an hour. Currently, the time to synchronize can only be set up through the backend. Contact support@cyberhaven.com to change the synchronization interval.

Mapping Okta users with Cyberhaven through custom attributes

If you have setup directory integration with Okta then you can leverage Cyberhaven's capability to establish mappings between endpoint users in Okta and Cyberhaven through custom attributes. This feature works for Okta integrated with a SCIM app. To configure custom atrribute mapping between Okta and Cyberhaven, follow the instructions.

1. Log into your Okta Admin Console and navigate to Directory > Profile Editor.

2. Select a SCIM app profile. The list of user attributes from the selected app is displayed.

3. Add a new custom attribute that you want to map to Cyberhaven. Click Add attribute.

4. Enter the following details.

a. Select the data type and enter a name for the attribute.

b. Enter a name and variable name to refer to this attribute.

c. Enter the external name for the attribute to be referenced during SAML communications with Cyberhaven.

d. Enter the external namespace as urn:ietf:params:scim:schemas:core:2.0:User. This is the SAML identifier for this attribute required to securely communicate with Cyberhaven.

e. Enter a description for the attribute.

f. Optionally, select the Enum checkbox to specify a set of values related to the attribute.

g. Define the attribute length.

h. Select the Attribute required checkbox to indicate that the attribute is required when using the SCIM app.

i. Set the scope of the attribute and mutability to read-only or hidden as recommended by Okta. Read more: Okta documentation

j. Click Save. The new custom attribute is added to the Attributes table.

5. Click on Mappings and then click on Okta User to SCIM tab.

6. Copy the name of the custom attribute from the SCIM app column.

7. Log into the Cyberhaven Console and navigate to Preferences > Directories and user mapping

8. From the list of integrations table click on the linked Okta integration. The WorkOS integration setup page is displayed with the current settings for the Okta integration.

9. On the integration settings page, click on Edit Attribute Map and in the dialog box paste the custom attribute in the field you want to map to Cyberhaven.

10. Click Save Mappings.

After the next synchronization between Cyberhaven and WorkOS the new attribute values for the endpoint users will be available in the Cyberhaven Console.

Viewing the status of user mappings

You can view the directory mapping status of all your endpoint users in the User Mapping tab. The "Mapped" status indicates that a user is linked to Cyberhaven through your corporate directory service using directory integration, while the "Unmapped" status means the user is not linked through directory integration. The table presents details including the email address of the mapped user, matching with their email in your directory service. It also shows the hostname, local username, the type and version of the Cyberhaven Sensor, and the name of the directory service used for mapping.

For unmapped users, the Details column displays a message explaining the reason behind the lack of mapping. The Troubleshooting section includes information about the messages in the Details column.

Troubleshooting

After linking the directory service to Cyberhaven if you are not seeing user data in your Cyberhaven UI, then verify that the Cyberhaven processes are not being blocked by a policy.

If the status details display the message "Email address reported by endpoint not found in user directory" then, ensure that the email address field in your user directory is mapped correctly to Cyberhaven.

For mapping with Okta, see the section, Mapping Okta users with Cyberhaven through custom attributes.

For mapping with Jamf, see the section, Enhancing User Mapping on macOS with Jamf.

If the status details display the message "Email address not reported by endpoint" then, ensure that user directory integration is set up correctly. See the instructions at the beginning of this article.

Change Log

Updated on 03/10/2025: Updated screenshot for selecting a directory provider.

Enhancing User Mapping on macOS with Jamf

Cyberhaven provides a solution to improve user mapping on macOS devices which are commonly managed through MDM solutions like Jamf instead of being enrolled in directory services like AD.

Although if you are using Apple Open Directory, then starting with Endpoint Sensor version 23.08, the Sensor has the capability to map endpoint users to the users in Open Directory based on their email address.

To verify that a user's email address is set up in Open Directory, open Terminal and run the following command.

BashCopy
dscl . -read /Users/$(whoami) EMailAddress
Command OutputDescription
EMailAddress: foo@example.comThis user's email address has been configured within Open Directory.
No such key: EMailAddressThis user's email address has not been configured within Open Directory. Proceed to the following section and set up email-based user mapping using your MDM solution.

Setting up email-based user mapping with Jamf

This solution is recommended for Jamf which is configured to use user email addresses as the username. In this case, you can leverage Jamf to set up an email-based mapping between endpoint users and your user directory service.

The solution requires you to create a new MDM profile

1. Log into Jamf Pro and navigate to Computers > Configuration Profiles. Click New.

2. Provide a name to identify this profile and adjust the scope of the deployment.

3. On the left navigation pane of the New Configuration Profile page, click Application & Custom Settings and then click External Applications. 4. To add Cyberhaven as an external application, click Add and select the source as Custom Schema.

5. In the Preference Domain field, add io.cyberhaven.lightbeam. 6. Click Add Schema and add the following JSON schema.

{
  "title": "Cyberhaven user mapping schema",
  "description": "User mapping from Jamf to the endpoint",
  "properties": {
    "mdm_username": {
      "title": "Username",
      "description": "The Jamf device owner",
      "property_order": 10,
      "type": "string"
    }
  }
}

7. In the Preference Domain Properties section under Username, enter $EMAIL.

NOTE Depending on your Jamf setup, the $EMAIL variable may need to be changed to $USERNAME. To verify this, review the computer's "User and Location" information.

8. Click Save.

When the custom schema is saved, the following screen is displayed.

The profile stores the mdm_username property within /Library/Managed\ Preferences/io.cyberhaven.lightbeam . The Sensor then retrieves this value and maps the field to the user directory service.

To verify that the configuration has been successfully applied to the endpoint, you can either check your MDM logs or the endpoint by running the following command.

BashCopy
defaults read /Library/Managed\ Preferences/io.cyberhaven.lightbeam

The output should contain the mdm_username variable.

The following is an example output.

NoneCopy
{ backend \= { "installer\_token" \= "eyJ......"; url \= "https://\<your-tenant\>.cyberhaven.io"; }; "mdm\_username" \= "<username@your.domain>"; version \= "2.0.1"; }

User Mapping on macOS with Kandji

This article provides instructions on how to map macOS users in Kandji with Cyberhaven using a custom MDM configuration profile. Cyberhaven uses the user’s email address as a unique identifier for mapping.

Before you begin, make sure that the devices where you want to deploy the MDM configuration profile are assigned to Device Users with a registered email address.

Deploy the MDM Profile

1. Copy the following MDM configuration profile into a text editor and save it as Cyberhaven-Kandji-UserMapping.mobileconfig.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-/Apple/DTD PLIST 1.0/EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>PayloadContent</key>
    <array>
      <dict>
        <key>PayloadDisplayName</key>
        <string>Cyberhaven User Mapping</string>
        <key>PayloadIdentifier</key>
        <string>io.cyberhaven.lightbeam.66ECCE2B-09FA-4890-9A15-CF9C03803736</string>
        <key>PayloadType</key>
        <string>io.cyberhaven.lightbeam</string>
        <key>PayloadUUID</key>
        <string>66ECCE2B-09FA-4890-9A15-CF9C03803736</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
        <key>mdm_username</key>
        <string>$EMAIL</string>
      </dict>
    </array>
    <key>PayloadDisplayName</key>
    <string>Cyberhaven User Mapping Profile</string>
    <key>PayloadIdentifier</key>
    <string>com.kandji.profile.custom.deb6d422-7700-47cb-86ca-9624ce666b37</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>deb6d422-7700-47cb-86ca-9624ce666b37</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
  </dict>
</plist>

2. In Kandji create a new custom profile. Navigate to Library and click Add new.

3. Select Custom Profile from the options and click on Add and Configure to begin configuring the profile.

4. Give the profile a name. For example, “Cyberhaven User Mapping Profile”.

5. Under Install on, select Mac.

6. Assign the profile to the blueprints to specify the devices where you want to deploy it.

7. Upload Cyberhaven-Kandji-UserMapping.mobileconfig to the profile.

Verify User Mapping

You can verify the user mapping by checking the .plist file on a device where the custom profile is deployed.

In a terminal window, run the following command to open and read the .plist file. defaults read /Library/Managed\ Preferences/io.cyberhaven.lightbeam

The field mdm_username will now be included in the .plist file, along with the device user’s email address.

The following is an example of a .plist file that includes mdm_username .

{
  PayloadUUID = “deb6d422-7700-47cb-86ca-9624ce666b37”;
  backend = {
    “dlp_url” = “https://test.cyberhaven.io”;
    “installer_token” = “eyJhbGcviHRxNWOHzmOs6go_tw.....”;
    url = “https://test.cyberhaven.io”;
  };
  “mdm_username” = “clu@cyberhaven.eu”;
  “use_system_extension” = 0;
  version = “2.0.5";
}
Tags:
Last updated on